生成API文档
【关于API Blueprint】
dingo api允许我们使用命令:
php artisan api:doc --output-file "D:\api.apib"
生成API Blueprint 1A 格式的文档;前提是我们已经为我们的控制器和方法写好了注释,比如:
<?php
namespace App\Http\Controllers\Api\V1;
use Illuminate\Http\Request;
use App\Http\Requests;
use App\Http\Controllers\Controller;
/**
* 用户资源
*
* <br/>[注意]:每个部门下的节点不能超过3万个。
*
* @Resource("Group User")
*/
class UserController extends ApiBaseController
{
/**
* 根据用户ID获取用户
*
* [需授权] 返回单个用户
*
* @Get("/api/user/ID")
* @Parameters({
* @Parameter("id", type="integer", required=true, description="用户ID")
* })
* @Request(headers={"Authorization": "Bearer token"})
* @Response(200, body={})
*/
public function show($id)
{
//
}
}
像上面这样写好注释后,使用 api:doc 命令行就会生成标准的 api blueprint 文档了。
【关于aglio】
那么,我们现在有了markdown写法的api blueprint文档了,怎么把它转换成可读的html文档呢?aglio神器就来了。aglio的github地址:https://github.com/danielgtaylor/aglio 注意安装aglio需要先安装NODE.JS,然后利用NPM安装即可:
npm install -g aglio
至于怎么安装node.JS 不是本文的关注点,各位自行搜索。
好了,安装aglio完毕我们就可以使用命令行生成可读的html格式的api文档了:
aglio -i "D:\api.apib" -o "D:\api.html"
生成的api文档如下:
到此,一套比较完善的api文档就新鲜出炉啦。
为了避免每次都要打2次命令,我们可以写一个命令脚本 ApiCreate.bat,比如:
@echo off
echo "API Create Command Tool"
echo Current directory is: %cd%
cd %cd%
::先生成api blueprint格式文档
call php artisan api:doc --output-file %cd%"\api.apib"
::用aglio工具转化成html文档 --theme-full-width
call aglio -i %cd%"\api.apib" -o %cd%"\public\api.html"
pause
这样以后要生产api文档,只要点击执行该bat脚本就可以啦。
关于生成api文档还有另外一个不错的工具:Swagger http://swagger.io/ 飘易会在另外的文章里单独说一说。